fix: sync Python type stubs (.pyi) with actual bindings and fix doc bugs

## Bug 1: Python type stubs missing 5 fields/classes

The pdf_inspector.pyi file was out of sync with the actual Python
bindings exposed via #[pyo3(get)] in src/python.rs. This breaks
IDE autocompletion and type checking (PyCharm, VS Code/Pylance, mypy)
for all Python users.

Added:
- PdfResult.ocr_reasons_by_page (python.rs:35)
- PageOcrReasons class with page and 
easons fields (python.rs:67-86)
- RegionText.ocr_reason (python.rs:136)
- PageMarkdown.ocr_reason (python.rs:193)
- PagesExtractionResult.ocr_reasons_by_page (python.rs:226)

## Bug 2: PdfResult.pages_needing_ocr indexing undocumented

PdfResult.pages_needing_ocr is 1-indexed (per python.rs:30) but
neither the .pyi stubs nor docs/python.md annotated this, while the
same field on PdfClassification was annotated as 0-indexed. Users
mixing both APIs would get wrong page numbers.

## Bug 3: README.md duplicate bullet character

The Markdown features table listed * twice in bullet prefixes.
The first should be �ullet (U+2022), matching the actual source code in
src/markdown/mod.rs:34 which uses: �ullet, dash, �sterisk, circle, illed-circle, open-circle.

## Bug 4: docs/python.md missing fields in type reference

The Types section was missing PageOcrReasons, RegionText class
definition, ocr_reason fields, and ocr_reasons_by_page fields.

## Evidence

Cross-referenced every #[pyo3(get)] attribute in src/python.rs
against the .pyi declarations and docs/python.md type reference.

Author: Sunil56224972

README.md

@@ -238,7 +238,7 @@ The converter handles:
 |---|---|
 | Headings (H1-H4) | Font size tiers relative to body text, with 0.5pt clustering |
 | Bold/italic | Font name patterns (Bold, Italic, Oblique) |
-| Bullet lists | `*`, `-`, `*`, `○`, `●`, `◦` prefixes |
+| Bullet lists | `•`, `-`, `*`, `○`, `●`, `◦` prefixes |
 | Numbered lists | `1.`, `1)`, `(1)` patterns |
 | Letter lists | `a.`, `a)`, `(a)` patterns |
 | Code blocks | Monospace fonts (Courier, Consolas, Monaco, Menlo, Fira Code, JetBrains Mono) and keyword detection |

docs/python.md

@@ -111,14 +111,19 @@ class PdfResult:                     # process_pdf / detect_pdf
     markdown: str | None             # extracted Markdown (None for detect_pdf)
     page_count: int
     processing_time_ms: int
-    pages_needing_ocr: list[int]
+    pages_needing_ocr: list[int]     # 1-indexed
+    ocr_reasons_by_page: list[PageOcrReasons]
     title: str | None
     confidence: float                # 0.0 - 1.0
     is_complex_layout: bool
     pages_with_tables: list[int]
     pages_with_columns: list[int]
     has_encoding_issues: bool        # broken font encodings — consider OCR fallback
 
+class PageOcrReasons:                # per-page OCR diagnostics
+    page: int                        # 1-indexed
+    reasons: list[str]               # machine-readable reason identifiers
+
 class PdfClassification:             # classify_pdf
     pdf_type: str
     page_count: int
@@ -140,14 +145,20 @@ class TextItem:                      # extract_text_with_positions
     is_strikeout: bool
     item_type: str
 
+class RegionText:                    # extract_text_in_regions
+    text: str
+    needs_ocr: bool
+    ocr_reason: str | None           # machine-readable OCR reason
+
 class PageRegionTexts:               # extract_text_in_regions
     page: int                        # 0-indexed
-    regions: list[RegionText]        # RegionText: text: str, needs_ocr: bool
+    regions: list[RegionText]
 
 class PagesExtractionResult:         # extract_pages_markdown
-    pages: list[PageMarkdown]        # PageMarkdown: page (0-indexed), markdown, needs_ocr
+    pages: list[PageMarkdown]        # PageMarkdown: page (0-indexed), markdown, needs_ocr, ocr_reason
     pages_with_tables: list[int]     # 1-indexed
     pages_with_columns: list[int]    # 1-indexed
     pages_needing_ocr: list[int]     # 1-indexed
+    ocr_reasons_by_page: list[PageOcrReasons]
     is_complex: bool                 # any page has tables or multi-column layout
 ```

pdf_inspector.pyi

@@ -10,13 +10,23 @@ class PdfResult:
     page_count: int
     processing_time_ms: int
     pages_needing_ocr: list[int]
+    """1-indexed page numbers that need OCR."""
+    ocr_reasons_by_page: list["PageOcrReasons"]
+    """Machine-readable OCR reasons by 1-indexed page."""
     title: Optional[str]
     confidence: float
     is_complex_layout: bool
     pages_with_tables: list[int]
     pages_with_columns: list[int]
     has_encoding_issues: bool
 
+class PageOcrReasons:
+    """OCR reasons for a single 1-indexed page."""
+    page: int
+    """1-indexed page number."""
+    reasons: list[str]
+    """Machine-readable OCR reason identifiers."""
+
 class PdfClassification:
     """Lightweight PDF classification result."""
     pdf_type: str
@@ -47,6 +57,8 @@ class RegionText:
     text: str
     needs_ocr: bool
     """True when the text should not be trusted."""
+    ocr_reason: Optional[str]
+    """Machine-readable OCR reason when the cause is known."""
 
 class PageRegionTexts:
     """Extracted text for one page's regions."""
@@ -62,6 +74,8 @@ class PageMarkdown:
     """Formatted markdown for this page (empty string when needs_ocr is True)."""
     needs_ocr: bool
     """True when text on this page is unreliable and OCR should be used instead."""
+    ocr_reason: Optional[str]
+    """Machine-readable OCR reason when the cause is known."""
 
 class PagesExtractionResult:
     """Per-page markdown output with document-wide layout classification."""
@@ -73,6 +87,8 @@ class PagesExtractionResult:
     """1-indexed pages where multi-column layout was detected."""
     pages_needing_ocr: list[int]
     """1-indexed pages that need OCR."""
+    ocr_reasons_by_page: list[PageOcrReasons]
+    """Machine-readable OCR reasons by 1-indexed page."""
     is_complex: bool
     """True if any page has tables or multi-column layout."""