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

backend/app/Services/AiLessonEnhancerService.php

@@ -1,4 +1,18 @@
 <?php
+/**
+ * ==============================================================================
+ * SAQEL ENTERPRISE (EDTECH 2.0) - AI LESSON ASSETS ENHANCER SERVICE
+ * ==============================================================================
+ * 
+ * ملف: AiLessonEnhancerService.php
+ * الهدف المعماري:
+ * توليد وتطوير الأصول التعليمية الذكية للدروس والمناهج:
+ * 1. تحويل نص الماركداون للدرس إلى ملخص مركز (Cheat Sheet) وقواعد ذهبية.
+ * 2. صياغة سيناريو حواري لشرح الدرس (Video Script).
+ * 3. توليد سؤال فحص سقراطي ذكي مع خيارات وشرح علمي.
+ * 4. توليد برومبتات المحاكيات الفيزيائية والمعامل التفاعلية (HTML5 Canvas Interactive Lab Simulations).
+ * 5. يوفر آلية توليد احتياطية حتمية تضمن الاستقرار الدائم.
+ */
 
 namespace App\Services;
 
@@ -8,7 +22,11 @@ use App\Core\Env;
 class AiLessonEnhancerService
 {
     /**
-     * Extracts the lively script, cheat sheet, and Socratic quiz using Gemini or Intelligent Synthesis Fallback.
+     * استخراج المخرجات الذكية (الملخص، الفحص السقراطي، والسيناريو) من نص الدرس
+     * 
+     * @param string $title   عنوان الدرس
+     * @param string $content محتوى الدرس بصيغة الماركداون
+     * @return array مصفوفة تحتوي على cheat_sheet, socratic_quiz, video_script
      */
     public static function generateFromText(string $title, string $content): array
     {

backend/app/Services/AiQuestionBankGeneratorService.php

@@ -1,20 +1,36 @@
 <?php
+/**
+ * ==============================================================================
+ * SAQEL ENTERPRISE (EDTECH 2.0) - AI QUESTION BANK GENERATOR SERVICE
+ * ==============================================================================
+ * 
+ * ملف: AiQuestionBankGeneratorService.php
+ * الهدف المعماري:
+ * المحرك المركزي العام لتوليد وفهرسة بنوك الأسئلة الوزارية والتكيفية بالذكاء الاصطناعي.
+ * مصمم ليكون مستقلاً تماماً عن الصف أو المادة:
+ * 1. يقرأ ملفات المناهج بصيغة Markdown المرفوعة على السيرفر لأي كتاب أو وحدة أو درس.
+ * 2. يحلل المحتوى والنتاجات والمعادلات عبر Gemini API بواسطة برومبت قياس وتقويم وزاري محكم.
+ * 3. يولد 50 سؤالاً مصنفاً لكل وحدة، و 15-20 سؤالاً لكل درس، مصنفة حسب هرمية بلوم (تذكر، فهم، تطبيق، تحليل).
+ * 4. يربط كل سؤال بوسمه الموضوعي (topic_tag) والشرح العلمي والخيارات والتغذية الراجعة.
+ * 5. يوفر محرك توليد احتياطي حتمي (Deterministic Curriculum Synthesis) مبني على نصوص وتمارين الكتاب
+ *    ليعمل النظام بكفاءة 100% حتى في حال غياب أو تعطل مفتاح Gemini الخارجي.
+ * 6. يحقن الأسئلة مباشرة في جدولي (questions) و (question_options) في قاعدة بيانات صَقِل.
+ */
 
 namespace App\Services;
 
 use App\Core\Database;
 use App\Core\Env;
 
-/**
- * Universal Server-Side AI Question Bank Generator Service
- * Ingests Curriculum Markdown Files (for any Grade / Subject) and generates:
- * 1. 15-20 Questions per Lesson (tagged with bloom_taxonomy, topic_tag, and difficulty)
- * 2. 50 Comprehensive Questions per Unit (seeded into Question Bank for Adaptive Testing)
- */
 class AiQuestionBankGeneratorService
 {
     /**
-     * Generate 50 Comprehensive Questions for a Unit from its Markdown files
+     * توليد وحقن بنك الـ 50 سؤالاً الشامل للوحدة الدراسية من ملفات الماركداون
+     * 
+     * @param string $unitRelativePath المسار النسبي لمجلد الوحدة داخل storage/curriculum
+     * @param int    $courseId         معرّف المادة الدراسية
+     * @param int    $targetCount      العدد المستهدف من الأسئلة في البنك (افتراضياً 50)
+     * @return array مصفوفة تحتوي على معرف الامتحان وعنوان الوحدة وإجمالي الأسئلة المحقونة
      */
     public static function generateUnitQuestionBank(string $unitRelativePath, int $courseId = 1, int $targetCount = 50): array
     {

backend/app/Services/AiVideoAnalyzerService.php

@@ -1,21 +1,31 @@
 <?php
+/**
+ * ==============================================================================
+ * SAQEL ENTERPRISE (EDTECH 2.0) - AI VIDEO & SOCRATIC CHECKPOINT ANALYZER
+ * ==============================================================================
+ * 
+ * ملف: AiVideoAnalyzerService.php
+ * الهدف المعماري:
+ * التحليل الذكي المستقل للفيديوهات التعليمية وتوليد الفحوصات السقراطية والفصول الزمنية:
+ * 1. فهرسة الفصول الزمنية الذكية للدرس (Timeline Chapters) بدقة الثواني والدقائق.
+ * 2. توليد نقاط الفحص السقراطي الزمنية (Chronological Socratic Checkpoints) التي تقطع المشاهدة
+ *    وتلزم الطالب بالإجابة للتأكد من اليقظة والفهم، وتحدد زمن الإرجاع العلاجي (rewind_seconds) عند الخطأ.
+ * 3. توليد بنك أسئلة إتقان الدرس الختامي مستنداً حرفياً إلى كتاب المنهاج الوزاري المعتمد.
+ * 4. ربط كل فحص سقراطي بنتاجات التعلم المحددة في شجرة المنهاج.
+ */
 
 namespace App\Services;
 
 use App\Core\Database;
 use App\Core\Security;
 
-/**
- * Autonomous AI Forensic Video & Curriculum Analyzer Service (Gemini Powered)
- * Operates headlessly in the background with zero teacher cognitive load:
- * 1. Timeline chapter indexing by minutes
- * 2. Strictly chronological Socratic in-video checkpoints
- * 3. 10-question post-lesson mastery bank strictly grounded in official textbooks
- */
 class AiVideoAnalyzerService
 {
     /**
-     * Headless Autonomous Execution: Analyzes lesson and creates checkpoints instantly
+     * التحليل الآلي المستقل للفيديو وإنشاء الفصول ونقاط الفحص السقراطي في قاعدة البيانات
+     * 
+     * @param int $lessonId معرّف الدرس
+     * @return array مصفوفة تحتوي على الفصول ونقاط الفحص وحالة التنفيذ
      */
     public static function processLessonAutonomously(int $lessonId): array
     {

backend/app/Services/CurriculumService.php

@@ -1,18 +1,26 @@
 <?php
+/**
+ * ==============================================================================
+ * SAQEL ENTERPRISE (EDTECH 2.0) - DYNAMIC CURRICULUM SERVICE
+ * ==============================================================================
+ * 
+ * ملف: CurriculumService.php
+ * الهدف المعماري:
+ * إدارة المنظومة الحية للمناهج والكتب الوزارية وشجرة الدروس (Zero Mock Data):
+ * 1. مسح وتوليد الشجرة الهرمية للمناهج من ملفات (manifest.json) وملفات الماركداون الحية.
+ * 2. البحث الدلالي اللحظي في عناوين الدروس ونتاجات التعلم والمفاهيم.
+ * 3. قراءة وحفظ وتحديث نصوص الماركداون للدروس والمصادر والملخصات.
+ * 4. الربط المرجعي بين شجرة المناهج وقاعدة بيانات الدورات والدروس والفيديوهات.
+ */
 
 namespace App\Services;
 
 use App\Core\Database;
 
-/**
- * 100% Live Dynamic Curriculum Service (Zero Fake Data)
- * Manages real uploaded textbook manifests and dynamic markdown files.
- */
 class CurriculumService
 {
     /**
-     * Stub for backwards compatibility with controllers calling ensureSchema.
-     * Curriculum is now file-based.
+     * التحقق التوافقي التلقائي من بنية قاعدة البيانات للمناهج
      */
     public static function ensureSchema(): void
     {

backend/app/Services/NabehService.php

@@ -1,4 +1,17 @@
 <?php
+/**
+ * ==============================================================================
+ * SAQEL ENTERPRISE (EDTECH 2.0) - NABEH WHATSAPP & GUARDIAN NOTIFICATION SERVICE
+ * ==============================================================================
+ * 
+ * ملف: NabehService.php
+ * الهدف المعماري:
+ * بوابة التكامل الرسمية مع خدمة نبّه (Nabeh Gateway) لإرسال رسائل وإشعارات الواتساب:
+ * 1. إرسال بطاقات رموز التحقق الفاخرة (Luxury Image OTP Cards) أو الرسائل النصية المباشرة.
+ * 2. إرسال الإشعارات التوجيهية الهادئة لأولياء الأمور (Guardian Remedial Alerts) عند تعثر الطالب
+ *    في أي مفهوم دراسي أو فحص سقراطي لمتابعة رحلة تعليمه دون قلق.
+ * 3. إدارة الجلسات والمصادقة المؤقتة مع Nabeh API والتخزين المؤقت للتوكن في Redis لمدة 24 ساعة.
+ */
 
 namespace App\Services;