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

backend/database_schema.sql

@@ -329,21 +329,21 @@ CREATE TABLE IF NOT EXISTS `video_quality_assessments` (
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
 
 -- ------------------------------------------------------------------------------
--- 12. Table: exams (الامتحانات: فحص سقراطي، امتحان درس، وحدة، وامتحان وزاري)
+-- 12. Table: exams (الامتحانات وبنوك الأسئلة التكيفية: فحص سقراطي، امتحان درس، وحدة، وامتحان وزاري)
 -- ------------------------------------------------------------------------------
 CREATE TABLE IF NOT EXISTS `exams` (
   `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
   `uuid` CHAR(36) NOT NULL UNIQUE,
   `course_id` BIGINT UNSIGNED NOT NULL,
-  `lesson_id` BIGINT UNSIGNED DEFAULT NULL,
+  `lesson_id` BIGINT UNSIGNED DEFAULT NULL COMMENT 'معرّف الدرس — يكون NULL في امتحانات نهاية الوحدة والامتحانات الشاملة',
   `created_by_id` BIGINT UNSIGNED DEFAULT NULL,
   `creator_type` ENUM('teacher', 'ai_adaptive', 'ministry_standard') NOT NULL DEFAULT 'ai_adaptive',
-  `scope` ENUM('in_video_checkpoint', 'lesson_exam', 'unit_exam', 'semester_final') NOT NULL DEFAULT 'in_video_checkpoint',
+  `scope` ENUM('in_video_checkpoint', 'lesson_exam', 'unit_exam', 'unit_comprehensive', 'semester_final') NOT NULL DEFAULT 'in_video_checkpoint' COMMENT 'نطاق الامتحان: فحص سقراطي، امتحان درس، أو امتحان وحدة شامل',
   `title` VARCHAR(255) NOT NULL,
   `description` TEXT DEFAULT NULL,
   `duration_minutes` INT UNSIGNED NOT NULL DEFAULT 30,
-  `timestamp_seconds` INT UNSIGNED NOT NULL DEFAULT 0,
-  `rewind_on_fail_seconds` INT UNSIGNED NOT NULL DEFAULT 45,
+  `timestamp_seconds` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT 'توقيت ظهور الفحص السقراطي أثناء تشغيل الفيديو',
+  `rewind_on_fail_seconds` INT UNSIGNED NOT NULL DEFAULT 45 COMMENT 'عدد الثواني التي يرجع إليها الفيديو عند الخطأ لترسيخ الفهم',
   `passing_percentage` DECIMAL(5, 2) NOT NULL DEFAULT 60.00,
   `total_points` INT UNSIGNED NOT NULL DEFAULT 100,
   `is_mandatory` TINYINT(1) NOT NULL DEFAULT 1,
@@ -366,14 +366,15 @@ CREATE TABLE IF NOT EXISTS `questions` (
   `exam_id` BIGINT UNSIGNED NOT NULL,
   `question_text` TEXT NOT NULL,
   `question_type` ENUM('multiple_choice', 'true_false', 'short_answer') NOT NULL DEFAULT 'multiple_choice',
-  `bloom_taxonomy` ENUM('recall', 'comprehension', 'application', 'analysis') NOT NULL DEFAULT 'comprehension',
-  `topic_tag` VARCHAR(150) DEFAULT NULL,
+  `bloom_taxonomy` ENUM('recall', 'comprehension', 'application', 'analysis') NOT NULL DEFAULT 'comprehension' COMMENT 'تصنيف بلوم المعرفي للقياس والتقويم',
+  `topic_tag` VARCHAR(150) DEFAULT NULL COMMENT 'الوسم الموضوعي الدقيق للمفهوم العلمي — يُستخدم لمحرك التعليم التكيفي وسد الثغرات',
   `points` INT UNSIGNED NOT NULL DEFAULT 10,
-  `explanation_text` TEXT DEFAULT NULL,
-  `ai_hint` TEXT DEFAULT NULL,
+  `explanation_text` TEXT DEFAULT NULL COMMENT 'خطوات الحل والتعليل العلمي النموذجي الموجه للطالب',
+  `ai_hint` TEXT DEFAULT NULL COMMENT 'تلميح ذكي يظهر للطالب عند التعثر دون إعطاء الإجابة المباشرة',
   `created_at` TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP,
   PRIMARY KEY (`id`),
   KEY `idx_questions_exam` (`exam_id`),
+  KEY `idx_questions_topic` (`topic_tag`),
   CONSTRAINT `fk_questions_exam` FOREIGN KEY (`exam_id`) REFERENCES `exams` (`id`) ON DELETE CASCADE
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
 
@@ -405,9 +406,9 @@ CREATE TABLE IF NOT EXISTS `exam_attempts` (
   `percentage` DECIMAL(5, 2) NOT NULL DEFAULT 0.00,
   `status` ENUM('passed', 'failed', 'needs_remediation', 'in_progress') NOT NULL DEFAULT 'in_progress',
   `time_spent_seconds` INT UNSIGNED NOT NULL DEFAULT 0,
-  `weak_topics_json` JSON DEFAULT NULL,
-  `ai_diagnostic_report` TEXT DEFAULT NULL,
-  `completed_at` TIMESTAMP NULL DEFAULT NULL,
+  `weak_topics_json` JSON DEFAULT NULL COMMENT 'مصفوفة JSON للمفاهيم التي تعثر فيها الطالب لتوجيهه علاجياً',
+  `ai_diagnostic_report` TEXT DEFAULT NULL COMMENT 'تقرير التشخيص السقراطي المولد بالذكاء الاصطناعي',
+  `completed_at` TIMESTAMP NULL DEFAULT NULL COMMENT 'وقت اكتمال المحاولة — يُستخدم لتتبع جاهزية الطالب وإشعار ولي الأمر',
   `created_at` TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP,
   PRIMARY KEY (`id`),
   KEY `idx_attempts_student` (`student_id`),
@@ -417,7 +418,7 @@ CREATE TABLE IF NOT EXISTS `exam_attempts` (
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
 
 -- ------------------------------------------------------------------------------
--- 15.5. Table: student_question_answers (تفاصيل إجابات الطالب)
+-- 15.5. Table: student_question_answers (تفاصيل إجابات الطالب للتحليل التكيفي)
 -- ------------------------------------------------------------------------------
 CREATE TABLE IF NOT EXISTS `student_question_answers` (
   `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
@@ -428,8 +429,11 @@ CREATE TABLE IF NOT EXISTS `student_question_answers` (
   `is_correct` TINYINT(1) NOT NULL DEFAULT 0,
   `points_awarded` DECIMAL(6,2) NOT NULL DEFAULT 0.00,
   `time_spent_seconds` INT UNSIGNED NOT NULL DEFAULT 0,
+  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
   PRIMARY KEY (`id`),
   KEY `idx_sqa_attempt` (`attempt_id`),
+  KEY `idx_sqa_student` (`student_id`),
+  KEY `idx_sqa_question` (`question_id`),
   CONSTRAINT `fk_sqa_attempt` FOREIGN KEY (`attempt_id`) REFERENCES `exam_attempts` (`id`) ON DELETE CASCADE,
   CONSTRAINT `fk_sqa_student` FOREIGN KEY (`student_id`) REFERENCES `students` (`id`) ON DELETE CASCADE,
   CONSTRAINT `fk_sqa_question` FOREIGN KEY (`question_id`) REFERENCES `questions` (`id`) ON DELETE CASCADE