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

backend/app/Controllers/AuthController.php

@@ -1,4 +1,19 @@
 <?php
+/**
+ * ==============================================================================
+ * SAQEL ENTERPRISE (EDTECH 2.0) - AUTHENTICATION & IDENTITY CONTROLLER
+ * ==============================================================================
+ * 
+ * ملف: AuthController.php
+ * الهدف المعماري:
+ * إدارة منظومة الهوية الرقمية والدخول الآمن والتحقق عبر الواتساب (OTP) في منصة صَقِل.
+ * يتولى هذا الملف المهام التالية:
+ * 1. إرسال رموز التحقق لمرة واحدة (OTP) عبر الواتساب بواسطة بوابة نبّه الرسمية (Nabeh Gateway).
+ * 2. التحقق من صحة الرمز وتوليد رموز JWT المشفرة بصلاحيات محددة (طالب، معلم، ولي أمر، مدير).
+ * 3. حماية الحسابات من هجمات الاختراق عبر بصمة الجهاز الرقمية (Device Fingerprinting).
+ * 4. إدارة جلسات تسجيل الدخول والخروج والتحقق من صلاحية التوكن (Token Introspection).
+ * 5. التحقق عبر الرقم الوطني لطلاب مديرية الثقافة العسكرية والمدارس الحكومية.
+ */
 
 namespace App\Controllers;
 
@@ -13,8 +28,11 @@ use App\Services\NabehService;
 class AuthController
 {
     /**
-     * Request OTP via WhatsApp (Nabeh Gateway)
+     * طلب رمز تحقق OTP جديد وإرساله عبر الواتساب بواسطة بوابة نبّه
      * POST /api/auth/otp/request
+     * 
+     * @param Request  $request  طلب الـ HTTP المحتوي على رقم الهاتف بصيغة دولية أو محلية
+     * @param Response $response كائن الاستجابة بحالة الإرسال وزمن انتهاء الصلاحية
      */
     public function requestOtp(Request $request, Response $response): void
     {

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
     {

backend/app/Controllers/ExamController.php

@@ -1,4 +1,20 @@
 <?php
+/**
+ * ==============================================================================
+ * SAQEL ENTERPRISE (EDTECH 2.0) - EXAM & ADAPTIVE ASSESSMENT CONTROLLER
+ * ==============================================================================
+ * 
+ * ملف: ExamController.php
+ * الهدف المعماري:
+ * إدارة منظومة القياس والتقويم والامتحانات التكيفية في منصة صَقِل.
+ * يقوم هذا الملف بالوظائف الجوهرية التالية:
+ * 1. استرجاع قائمة الامتحانات والفحوصات السقراطية (in_video_checkpoint, lesson_exam, unit_exam).
+ * 2. محرك الاختيار التكيفي (Adaptive 60/40 Engine): فحص نقاط ضعف الطالب وسحب 60% من أسئلة الامتحان
+ *    من المفاهيم التي تعثر فيها الطالب سابقاً لسد الثغرات وتحقيق الإتقان، و 40% من باقي مفاهيم الوحدة.
+ * 3. استلام وتصحيح إجابات الامتحانات لحظياً وحساب نسبة الإتقان وتوليد تقرير التشخيص الذكي (AI Diagnostic Report).
+ * 4. إطلاق إشعار الواتساب التوجيهي الهادئ لولي الأمر عبر بوابة "نبّه" عند رصد حاجة الطالب للمعالجة.
+ * 5. حساب مؤشرات الجاهزية للتوجيهي ونقاط الإتقان لكل مادة دراسية.
+ */
 
 namespace App\Controllers;
 
@@ -10,8 +26,11 @@ use App\Core\Validator;
 class ExamController
 {
     /**
-     * List exams for a specific course/lesson/scope
+     * جلب قائمة الامتحانات المتاحة لمادة أو درس معين مع عدد الأسئلة
      * GET /api/exams?course_id=1&lesson_id=2&scope=in_video_checkpoint
+     * 
+     * @param Request  $request  طلب الـ HTTP المحتوي على معاملات التصفية (course_id, lesson_id, scope)
+     * @param Response $response كائن الاستجابة لإرجاع مصفوفة الامتحانات بصيغة JSON
      */
     public function getExams(Request $request, Response $response): void
     {
@@ -50,8 +69,17 @@ class ExamController
     }
 
     /**
-     * Get single exam with questions and sanitized options
+     * استرجاع تفاصيل الامتحان مع الأسئلة والخيارات المنقحة (ومحرك الاختيار التكيفي 60/40)
      * GET /api/exams/{id}
+     * 
+     * آلية العمل:
+     * 1. التحقق من وجود الامتحان، وإذا كان غير مفهرس يتم استدعاء باني الأسئلة التلقائي للوحدة الأولى.
+     * 2. تطبيق خوارزمية التعلم التكيفي (Adaptive Sampling): إذا كان بنك الأسئلة يحتوي على أكثر من 15 سؤالاً،
+     *    يتم فحص تاريخ الطالب واستخراج المفاهيم التي أخطأ فيها سابقاً وسحب 60% من أسئلة الامتحان منها.
+     * 3. تنقيح خيارات الإجابة وحجب حقل (is_correct) عن الطالب منعاً للغش وإظهاره فقط للمعلم أو الأدمن.
+     * 
+     * @param Request  $request  طلب الـ HTTP المحتوي على معرف الامتحان في المسار ومعرف الطالب المصادق عليه
+     * @param Response $response كائن الاستجابة لإرجاع كائن الامتحان بأسئلته الـ 15 التكيفية
      */
     public function getExamDetails(Request $request, Response $response): void
     {
@@ -141,8 +169,19 @@ class ExamController
     }
 
     /**
-     * Submit Exam Attempt & Calculate Instant AI Diagnostic Evaluation
+     * تصحيح الامتحان لحظياً بالذكاء الاصطناعي وتوليد التقرير التشخيصي وإشعار ولي الأمر
      * POST /api/exams/{id}/submit
+     * 
+     * الوظائف المنجزة:
+     * 1. التحقق من إجابات الطالب ومقارنتها بالخيارات الصحيحة وحساب مجموع النقاط ونسبة الإتقان المئوية.
+     * 2. تسجيل كل إجابة في جدول (student_question_answers) لبناء ملف الضعف والقوة للتعلم التكيفي المستقبلي.
+     * 3. توليد تقرير تشخيصي ذكي (AI Diagnostic Report) يبرز المفاهيم المتقنة والمفاهيم المتعثر فيها بدقة.
+     * 4. فحص شرط النجاح: إذا كانت النتيجة أقل من نسبة النجاح، يتم ضبط الحالة على needs_remediation
+     *    وإطلاق رسالة توجيهية هادئة عبر الواتساب لولي الأمر عبر بوابة نبّه (Nabeh Gateway).
+     * 5. تحديث جدول إتقان الطالب (student_course_mastery) ونقاط جاهزية التوجيهي.
+     * 
+     * @param Request  $request  طلب الـ HTTP المحتوي على الإجابات ووقت المحاولة
+     * @param Response $response كائن الاستجابة بالنتيجة والتقرير وتفاصيل الحل النموذجي
      */
     public function submitExam(Request $request, Response $response): void
     {
@@ -350,8 +389,11 @@ class ExamController
     }
 
     /**
-     * Get Student Mastery & Tawjihi Readiness Analytics
+     * استرجاع مقاييس إتقان الطالب ومؤشر الجاهزية لامتحان التوجيهي
      * GET /api/student/progress/mastery?course_id=1
+     * 
+     * @param Request  $request  طلب الـ HTTP المحتوي على معرف الطالب ومعرف المادة
+     * @param Response $response كائن الاستجابة بنسبة الإتقان والمحاولات الأخيرة
      */
     public function getMastery(Request $request, Response $response): void
     {
@@ -386,6 +428,10 @@ class ExamController
         ]);
     }
 
+    /**
+     * فحص التوافقية الذاتية وترقية جداول الامتحانات والتقييم في قاعدة البيانات
+     * تقوم بإنشاء جدول (student_question_answers) والتأكد من وجود عمود (completed_at) وتوسيع الـ ENUM
+     */
     public static function ensureSchema(): void
     {
         try {
@@ -424,6 +470,11 @@ class ExamController
         }
     }
 
+    /**
+     * التهيئة والتوليد الذاتي لامتحان الوحدة الأولى الشامل وحقن الأسئلة من بنك الذكاء الاصطناعي
+     * 
+     * @return int معرف الامتحان في قاعدة البيانات
+     */
     public static function seedUnit1ComprehensiveExam(): int
     {
         self::ensureSchema();

backend/app/Controllers/VideoController.php

@@ -1,4 +1,19 @@
 <?php
+/**
+ * ==============================================================================
+ * SAQEL ENTERPRISE (EDTECH 2.0) - VIDEO STREAMING & SOCRATIC PLAYBACK CONTROLLER
+ * ==============================================================================
+ * 
+ * ملف: VideoController.php
+ * الهدف المعماري:
+ * إدارة منظومة بث الفيديو الرقمي، وتوليد الفحوصات السقراطية، وبث HLS المجزأ عبر Cloudflare R2.
+ * يتولى هذا الملف المهام التالية:
+ * 1. رفع ملفات الفيديو المباشرة وتحويلها وتجزئتها إلى مقاطع HLS مشفرة لحماية الملكية الفكرية.
+ * 2. تشغيل التحليل السمعي-البصري بالذكاء الاصطناعي (AiVideoAnalyzerService) لتوليد الفصول الزمنية ونقاط الفحص السقراطي.
+ * 3. بث الفيديو عبر روابط مؤقتة آمنة (Byte-Range Streaming و HLS Playlists).
+ * 4. تزويد مشغل الفيديو في فلاتر ببيانات التشغيل (الروابط، الفصول، المعلم المعتمد، ونقاط التوقف السقراطية).
+ * 5. حفظ تقدم المشاهدة اللحظي لكل طالب في جدول (lesson_progress) وإدارة الاستئناف التلقائي.
+ */
 
 namespace App\Controllers;
 
@@ -13,8 +28,11 @@ use App\Services\CurriculumService;
 class VideoController
 {
     /**
-     * Upload Video directly via API, transcode HLS, and trigger Autonomous Gemini AI Analysis
+     * رفع فيديو الشرح مباشرة عبر واجهة البرمجة وتوليد HLS وبدء التحليل السقراطي بالذكاء الاصطناعي
      * POST /api/teacher/videos/upload-direct
+     * 
+     * @param Request  $request  طلب الـ HTTP المحتوي على ملف الفيديو والبيانات الوصفية
+     * @param Response $response كائن الاستجابة بحالة الرفع ومعرف الدرس ورابط المشاهدة
      */
     public function uploadDirect(Request $request, Response $response): void
     {