feat(subscription): implement effective plan logic and update free plan features

docs/api/subscription.md

@@ -8,6 +8,8 @@
 
 لیست پنل‌ها با دوره‌های فعال (عمومی — بدون auth).
 
+> پلن `free`: همه امکانات (`patient_records`, `services`, `sms_panel`, `insurance`) فعال‌اند؛ تنها محدودیت آن تعداد منشی (`max_secretaries`) است.
+
 **Response 200:**
 ```json
 {
@@ -18,7 +20,7 @@
       "name": "free",
       "level": 0,
       "max_secretaries": 1,
-      "features": { "patient_records": false, "services": false, "sms_panel": false },
+      "features": { "patient_records": true, "services": true, "sms_panel": true, "insurance": true },
       "active": true,
       "periods": []
     },
@@ -71,12 +73,13 @@
       "days_remaining": 30,
       "is_active": true
     },
-    "used_trial": false
+    "used_trial": false,
+    "effective_plan": { "name": "basic", "level": 1, "max_secretaries": 3, "features": {...} }
   }
 }
 ```
 
-اگر اشتراک فعالی نداشت `subscription` برابر `null` است.
+اگر اشتراک فعالی نداشت `subscription` برابر `null` است، اما `effective_plan` همیشه مقدار دارد: پلن اشتراک فعال، یا در نبود اشتراک، **پلن پیش‌فرض `free`**. فرانت‌اند برای تعیین دسترسی به امکانات (`hasFeature`) باید از `effective_plan` استفاده کند (نه `subscription`) تا کاربرانِ بدون اشتراک هم امکانات پلن free را داشته باشند. `subscription`/`hasPlan` صرفاً برای نمایش وضعیت اشتراک پولی است.
 
 ---
 
@@ -143,7 +146,7 @@ callback درگاه پرداخت — پس از پرداخت موفق، `ClinicSu
 ## Admin Endpoints
 
 ### GET /api/v1/admin/subscription/plans
-**Permission:** `ROLE_ADMIN` — لیست همه پنل‌ها
+**Permission:** `ROLE_ADMIN` — لیست **همه** پلن‌ها شامل غیرفعال‌ها (بر خلاف endpoint عمومی که فقط فعال‌ها را برمی‌گرداند). هر پلن فیلد `active` دارد و `periods` همیشه یک آرایه است (فقط دوره‌های فعال).
 
 ### POST /api/v1/admin/subscription/plan
 **Permission:** `ROLE_ADMIN`
@@ -157,9 +160,23 @@ callback درگاه پرداخت — پس از پرداخت موفق، `ClinicSu
 }
 ```
 
+**خطاها:**
+
+| کد | HTTP | شرح |
+|----|------|-----|
+| ERR_VALIDATION_001 | 422 | `name` یا `level` ارسال نشده |
+| ERR_VALIDATION_001 | 422 | پلنی با این نام از قبل وجود دارد (نام یکتاست) |
+
 ### PATCH /api/v1/admin/subscription/plan/{uuid}
 **Permission:** `ROLE_ADMIN` — ویرایش پنل (همه فیلدها اختیاری)
 
+**خطاها:**
+
+| کد | HTTP | شرح |
+|----|------|-----|
+| ERR_SUBSCRIPTION_NOT_FOUND | 404 | پلن یافت نشد |
+| ERR_VALIDATION_001 | 422 | نام جدید متعلق به پلن دیگری است |
+
 ### POST /api/v1/admin/subscription/period
 **Permission:** `ROLE_ADMIN`