feat(settlement): add receipt handling and detail view for settlements

docs/api/admin.md

@@ -1052,3 +1052,27 @@ Reject a pending request. **Permission:** `ROLE_ADMIN`
   ]
 }
 ```
+
+### GET `/api/v1/admin/settlement/{uuid}`
+
+جزئیات یک درخواست تسویه (برای صفحه‌ی `/admin/settlements/{uuid}`). **Permission:** `ROLE_ADMIN`
+
+**Response `200`:**
+```json
+{
+  "success": true,
+  "data": {
+    "uuid": "...",
+    "representation_name": "نماینده یزد",
+    "representation_mobile": "09390036732",
+    "amount": 500000,
+    "status": "pending",
+    "bank_card": "6037...", "bank_name": "ملت", "bank_iban": "IR...", "bank_owner": "...",
+    "reject_reason": null,
+    "requested_at": "2026-06-24T...", "processed_at": null
+  }
+}
+```
+تأیید/رد از طریق `POST /api/v1/settlement/{uuid}/approve|reject` (در `docs/api/settlement.md`).
+
+**Errors:** `NOT_FOUND` (404) — درخواست یافت نشد.

docs/api/settlement.md

@@ -258,3 +258,39 @@ Updated settlement object with `status: "rejected"`.
 ## FinancialBreakdown (لاگ مالی)
 
 علاوه بر تسویه‌حساب دستی، کیف‌پول نماینده به‌صورت خودکار از طریق `CommissionService` هنگام پرداخت موفقِ نوبت/اشتراک شارژ می‌شود (`WalletTransaction` credit). هر واریز یک ردیف `FinancialBreakdown` ثبت می‌کند که تفکیک کامل تراکنش (ناخالص، هزینه پیامک، مالیات، خالص، درصد و سهم پورسانت، سهم سیستم) را نگه می‌دارد. ثبت idempotent است (بر اساس `payment_id`). گزارش‌ها از طریق `GET /api/v1/admin/financial-breakdowns` و `GET /api/v1/admin/financial-summary` در دسترس‌اند — جزئیات در `docs/api/admin.md`.
+
+---
+
+## رسید پرداخت و ثبت پرداخت نهایی (ROLE_ADMIN)
+
+> منطق کیف‌پول: مبلغ هنگام **ثبت درخواست** از کیف‌پول نماینده کسر (reserve/debit) می‌شود؛ **رد** آن را برمی‌گرداند (credit). تأیید و پرداختِ نهایی کیف‌پول را دوباره دست نمی‌زنند (جلوگیری از double-debit).
+
+### POST `/file/upload/clinic_pro/settlement/receipt`
+
+آپلود تصویر رسید پرداخت. بدنه = محتوای خام فایل؛ هدر `Content-Disposition: filename="..."`. **Permission:** `ROLE_ADMIN`
+
+**Response `200`:**
+```json
+{ "success": true, "data": { "uuid": "...", "url": "/uploads/settlements/receipts/2026-06/...", "filename": "...", "filemime": "image/jpeg" } }
+```
+
+### POST `/api/v1/settlement/{uuid}/paid`
+
+ثبت پرداخت نهایی با رسید. فقط روی تسویه‌ی **approved**. وضعیت → `paid` و `receipt` ذخیره می‌شود. کیف‌پول تغییر نمی‌کند. **Permission:** `ROLE_ADMIN`
+
+**Request Body:**
+```json
+{ "receipt": "/uploads/settlements/receipts/2026-06/..." }
+```
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `receipt` | string | ✅ | URL رسیدِ آپلودشده |
+
+**Response `200`:** آبجکت تسویه (شامل `receipt` و `status: "paid"`).
+
+**Errors:**
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_NOT_FOUND_001` | 404 | درخواست یافت نشد |
+| `ERR_VALIDATION_001` | 422 | تسویه approved نیست |
+| `ERR_VALIDATION_002` | 422 | `receipt` خالی (`field: receipt`) |