docs: add comprehensive map functionality and api details

README.md

@@ -87,6 +87,28 @@ Manages user sessions.
 -   **`login(identifier, password, type)`**: Validates credentials against `MOCK_USERS`.
 -   **`user` object**: Contains `role`, `name`, `id`, and permissions.
 
+## 🗺️ Map Functionality & Geospatial Logic
+
+The map interface (`src/pages/Maps.jsx`) is the core operational view, overlaying business data on real-world geography.
+
+### 1. Visualization & Overlays
+-   **Rendering Engine**: Powered by `react-leaflet`.
+-   **Polygons**: Property boundaries are drawn using the `Polygon` component, taking an array of `[lat, lng]` coordinates.
+-   **Status Styling**:
+    -   **Hot Lead**: Red Fill (`#ef4444`)
+    -   **Customer**: Emerald Fill (`#10b981`)
+    -   **Renovated**: Blue Fill (`#3b82f6`)
+    -   **Neutral**: Zinc Fill (Default)
+
+### 2. Interaction & Data Retrieval
+-   **Click-to-Reveal**: Clicking a polygon triggers `onSelect(property)`, opening the **Property Drawer**.
+    -   **Returns**: Full `propertyData` (Address, Build Year, Value) and `ownerData` (Name, Contact, Intent).
+-   **Reverse Geocoding (New Property)**:
+    -   **Trigger**: Clicking an empty map area (Field Agents only).
+    -   **API Call**: `https://nominatim.openstreetmap.org/reverse`
+    -   **Parameters**: `lat`, `lon`, `format='json'`.
+    -   **Return**: Returns a JSON object where `display_name` is extracted as the property address.
+
 ## 📚 Function Documentation
 
 ### `useMockStore: addMeeting(meeting)`