docs: add comprehensive architecture and logistics guide for multi-carrier pickup scheduling

documentation/pickup_scheduling_architecture.md

@@ -127,3 +127,29 @@ class Order(models.Model):
 - **Delhivery**: `DelhiveryActivityLog` (records every HTTP status, endpoint, request headers/payload, and response).
 - **Ekart**: `EkartActivityLog` (records all token, dispatch-date, and tracking calls).
 - **Shadowfax**: `ActivityLog` (records forward/reverse order dispatch and tracking calls).
+
+---
+
+## 6. Delhivery One Web Portal ("Add to Pickup") vs. REST API Workflow
+
+### 6.1. Why Orders in the Web Portal Show "Add to Pickup"
+- In the **Delhivery One Web Dashboard** (`one.delhivery.com/orders/forward/ready-to-ship`), manifested orders display an **"Add to Pickup"** button.
+- The web portal has its own internal UI workflow:
+  1. A dashboard user selects orders and clicks "Add to Pickup".
+  2. The portal prompts for date, time slot, and warehouse, and generates a Pickup Request (PUR).
+  3. Once submitted *through the web UI*, the portal UI groups those orders and displays them under the **"Ready For Pickup"** tab.
+
+### 6.2. How the REST API Operates
+- In Delhivery's official developer API, order creation and pickup requests are decoupled:
+  1. **Order Manifestation API (`POST /api/cmu/create.json`)**:
+     - Registers the consignment, creates the AWB, and maps it to the warehouse (`SAM`).
+  2. **Pickup Request Creation API (`POST /fm/request/new/`)**:
+     - Dispatches a field executive to the warehouse (`SAM`) with `pickup_date`, `pickup_time`, and `expected_package_count`.
+     - **The REST API does not accept a list of waybills/orders**. It books the executive visit for the entire warehouse.
+- **Physical Scan & Handoff**:
+  - The Delhivery delivery executive arrives at the warehouse holding the active **Pickup Request ID (e.g. `#328095871`)**.
+  - The driver scans the physical barcode/AWB label on each package using their handheld scanner.
+  - The scan links the package to the pickup run and immediately transitions the order status from manifested directly to **"In Transit" / "Picked Up"**.
+- **Tradhox User Experience**:
+  - In Tradhox Supplier Central, once an order is manifested and scheduled, Tradhox surfaces the active **Pickup Request ID (`PR #328095871`)** and **`PICKUP SCHEDULED`** badge.
+  - Merchants do not need to manually click "Add to Pickup" inside the Delhivery One portal; the courier executive will collect all ready packages for warehouse `SAM`.