Enrich full codebase with architectural Arabic docblocks and synchronize database_schema.sql with live database

backend/app/Controllers/CurriculumController.php

@@ -1,4 +1,21 @@
 <?php
+/**
+ * ==============================================================================
+ * SAQEL ENTERPRISE (EDTECH 2.0) - CURRICULUM & STUDIO CONTROLLER
+ * ==============================================================================
+ * 
+ * ملف: CurriculumController.php
+ * الهدف المعماري:
+ * إدارة منظومة تفريغ وفهرسة كتب المناهج الوزارية واستوديو المناهج (Curriculum Studio).
+ * يتولى هذا الملف المهام التالية:
+ * 1. استلام كتب الـ PDF الوزارية المرفوعة وتمريرها لعمال الخلفية لاستخراج شجرة الماركداون.
+ * 2. متابعة حالة مهام المعالجة والتفريغ التلقائي وإرجاع سجلات التشغيل الحية (Live Logs).
+ * 3. استرجاع الشجرة الهرمية للمنهاج (المرحلة، المادة، الفصل، الوحدة، الدرس).
+ * 4. حفظ وتحديث محتوى ملفات الماركداون للدروس وربطها مع قاعدة البيانات.
+ * 5. توليد الملخصات الذكية (Cheat Sheets) والفحوصات السقراطية عبر Gemini.
+ * 6. توليد وتحديث بنوك الأسئلة (50 سؤالاً للوحدة) بالذكاء الاصطناعي بنقرة واحدة من الاستوديو.
+ * 7. استضافة ورفع ملفات الفيديو مباشرة وربطها بالدروس.
+ */
 
 namespace App\Controllers;
 
@@ -10,7 +27,11 @@ use App\Services\CurriculumExtractorService;
 class CurriculumController
 {
     /**
-     * Upload and Queue Real Ministry PDF Document for Deep Extraction
+     * استلام ورفع كتاب المنهاج الوزاري بصيغة PDF وجدولته في طابور المعالجة المعمقة
+     * POST /api/curriculum/upload-pdf
+     * 
+     * @param Request  $request  طلب الـ HTTP المحتوي على ملف الـ PDF المرفوع
+     * @param Response $response كائن الاستجابة بمعرف المهمة ومسار المتابعة
      */
     public function uploadPdf(Request $request, Response $response): void
     {