```txt
=== Cordial Contest & Voting System ===
Contributors: cordialtec
Tags: contests, voting, competition, contestants, leaderboard, woocommerce, forminator, competition system, voting system, contest management
Requires at least: 6.0
Tested up to: 6.6
Stable tag: 1.0.2
License: GPL v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A comprehensive competition and voting management system with real-time leaderboards, WooCommerce integration, and universal form support.

== Description ==

The Cordial Contest & Voting System is a complete competition infrastructure that transforms your WordPress site into a powerful contest and voting platform. Perfect for talent shows, photo contests, cooking competitions, awards, and any event that requires contestant management and public voting.

= WHY CHOOSE CORDIAL CONTESTS? =

🎯 **Complete Competition Lifecycle**
Manage everything from contestant applications to winner announcements in one integrated system.

👥 **Professional Contestant Profiles**
Rich contestant profiles with personal information, social media links, photo galleries, and video introductions.

🗳️ **Monetized Voting System**
Seamless WooCommerce integration turns votes into revenue with flexible product detection.

🏆 **Real-time Leaderboards**
Dynamic rankings that update instantly as votes come in, with multiple display formats.

📝 **Universal Form Compatibility**
Works with Forminator, WPForms, Gravity Forms, or any form plugin that supports custom post types.

⚙️ **Enterprise-grade Administration**
Comprehensive settings, security measures, and performance optimization out of the box.

= CORE FEATURES =

**Competition Management**
- Custom competition post type with detailed organization
- Competition dates, times, and automatic status transitions
- Entry fee configuration and prize management
- Voting rules, limits, and cooldown periods
- Maximum contestant limits and auto-approval settings
- Competition rules, eligibility criteria, and terms

**Contestant Management**
- Complete contestant profiles with personal information
- Age calculation from date of birth
- Social media integration (Facebook, Instagram, Twitter, YouTube, TikTok, Website)
- Visual media management with video URLs and photo galleries
- Competition history tracking with 6 display formats
- Application status workflow (pending, approved, rejected, disqualified)
- Automatic entry code generation
- Featured contestant highlighting

**Smart Voting Engine**
- Language-agnostic vote product detection (Auto, Manual ID, Keyword Search)
- WooCommerce cart integration with contestant-specific voting
- Anti-cheating measures with IP tracking and vote cooldowns
- Race condition protection for accurate vote counting
- Vote history tracking and analytics
- Automatic vote processing after payment confirmation

**Leaderboard & Ranking System**
- Dual ranking systems: Standard (1,2,2,4) and Dense (1,2,2,3)
- Time-based rankings: Today, This Week, Last Week, Last Month, All Time
- Competition-specific or global leaderboard views
- Customizable trophy and medal display
- Real-time ranking updates with caching for performance

**Form Integration Framework**
- Universal compatibility with any form plugin
- Automatic competition assignment via URL parameters
- Complete field mapping for all contestant data
- Frontend application system with Apply Now buttons
- Post data handling for contestant creation

**Administration & Security**
- 7-tab settings panel for complete configuration
- Email notifications system (votes, applications, winners, admin alerts)
- Performance caching with configurable durations
- Debug mode for troubleshooting
- Data cleanup and maintenance tools
- Comprehensive security and spam protection

== Installation ==

= STEP 1: PLUGIN INSTALLATION =

1. Upload the entire `cordial-contest` folder to `/wp-content/plugins/`
2. Activate the plugin through 'Plugins' in WordPress admin
3. The plugin will create necessary database tables automatically

= STEP 2: WOOCOMMERCE SETUP (Required for Voting) =

1. Ensure WooCommerce is installed and activated
2. Create a product for votes (can be free or paid)
3. Go to Cordial Contests > Settings > Voting
4. Configure vote detection method:
   - **Auto-detect**: System automatically finds vote products
   - **Manual ID**: Specify exact product ID
   - **Keyword Search**: Search by product title keyword

= STEP 3: CREATE YOUR FIRST COMPETITION =

1. Go to Cordial Contests > Add Competition
2. Fill in competition details:
   - Competition Dates & Times
   - Entry & Prize Information  
   - Voting Configuration
   - Competition Rules
   - Status Management
3. Publish the competition

= STEP 4: SET UP APPLICATION FORMS =

Option A: Use Built-in Apply Now Button
- Add `[apply_now_button]` shortcode to competition pages
- System automatically handles competition assignment

Option B: Custom Form Setup
- Create a form with post_type set to "contestant"
- Map form fields to contestant meta fields
- Include hidden field for `current_competition_id` with query parameter `competition_id`

== Frequently Asked Questions ==

= How does the voting system work? =

The voting system integrates with WooCommerce:
1. Users click "VOTE" on contestant cards
2. They select vote quantity and proceed to checkout
3. After payment, votes are automatically counted
4. Leaderboards update in real-time
5. Vote history is tracked for analytics

= Can I use free voting (no payment required)? =

Yes! Create a $0 product in WooCommerce and set it as your vote product. The system will still track votes through the cart process.

= What form plugins are supported? =

All major form plugins are supported:
- Forminator (recommended)
- WPForms
- Gravity Forms  
- Formidable Forms
- WP User Frontend
- Any plugin that can create custom post types and set post meta

= How do contestants get assigned to competitions? =

Automatically through form submission:
1. Competition pages have Apply Now buttons with `?competition_id=123`
2. Forms capture this parameter and save to `current_competition_id`
3. Contestants are automatically linked to the correct competition

= Can contestants enter multiple competitions? =

Yes! The system tracks competition history automatically. When a contestant applies to a new competition, it's added to their history while maintaining their current competition assignment.

= How are rankings calculated? =

Two ranking systems are available:
- **Standard Ranking**: 1st, 2nd, 2nd, 4th (ties get same rank, next rank skips)
- **Dense Ranking**: 1st, 2nd, 2nd, 3rd (ties get same rank, next rank continues)

= Can I customize the appearance? =

Yes! All shortcodes accept styling parameters, and you can override CSS in your theme. The plugin uses semantic CSS classes for easy customization.

== Shortcodes ==

= APPLICATION BUTTON =

`[apply_now_button]` - Displays application button for current competition

*Parameters:*
- `width` - Button width (200px, 50%, 10rem, auto)
- `height` - Button height 
- `background` - Background color (#3bb44a, blue, rgba(0,0,0,0.5))
- `color` - Text color (white, #333)
- `font_size` - Text size (16px, 1.2rem)
- `font_weight` - Text weight (normal, bold, 600)
- `border_radius` - Corner rounding (8px, 50%)
- `margin` - Outer spacing (10px, 1rem 2rem)
- `padding` - Inner spacing (10px 20px)
- `border` - Border styling (1px solid #ccc)
- `hover_background` - Hover state background
- `hover_color` - Hover state text color
- `button_text` - Button text ("Apply Now", "Join Competition")
- `target` - Link target (_blank, _self)
- `class` - Additional CSS classes

*Examples:*
`[apply_now_button]` - Default green button
`[apply_now_button width="200px" background="#ff6b6b" color="white" font_size="1.1rem" border_radius="25px" button_text="Enter Contest"]` - Custom red button
`[apply_now_button width="100%" background="transparent" color="#333" border="2px solid #333" hover_background="#333" hover_color="white"]` - Outline button

= CONTESTANT DISPLAY =

`[single_contestant_card]` - Displays individual contestant card with voting interface

`[contestant_loop]` - Displays grid of contestant cards

*Parameters for contestant_loop:*
- `competition_id` - Filter by competition ID
- `posts_per_page` - Number to display (-1 for all)
- `columns` - Grid columns (2 or 3)
- `orderby` - Sort field (date, vote_count, random, title)
- `order` - Sort direction (ASC, DESC)
- `author` - Filter by author ID
- `post__in` - Include specific IDs (comma-separated)
- `post__not_in` - Exclude specific IDs
- `meta_key` - Filter by custom field
- `meta_value` - Value for meta query
- `pagination` - Enable pagination (yes/no)

*Examples:*
`[contestant_loop]` - All contestants in 3-column grid
`[contestant_loop competition_id="123" columns="2" orderby="vote_count" order="DESC"]` - Competition contestants sorted by votes
`[contestant_loop posts_per_page="12" pagination="yes"]` - Paginated contestant grid

= LEADERBOARDS & RANKINGS =

`[leaderboard]` - Displays competition leaderboard

*Parameters:*
- `competition_id` - Specific competition (0 for all)
- `time_period` - Time filter (today, this_week, last_week, last_month, all_time)
- `limit` - Number of entries (default: 50)

`[contestant_votes]` - Displays vote count for current contestant

`[contestant_rank]` - Displays standard rank (1,2,2,4) for current contestant

`[leaderboard_rank]` - Displays dense rank (1,2,2,3) for current contestant

`[competition_history]` - Displays contestant competition history

*Parameters for competition_history:*
- `contestant_id` - Specific contestant ID (default: current)
- `format` - Display format:
  - `detailed_list` - Bulleted list with status and dates
  - `timeline_pipe` - Timeline view with symbols
  - `status_grouped` - Grouped by competition status
  - `simple_comma` - Simple comma-separated list
  - `achievement_emoji` - Emoji-based achievement display
  - `position_ranking` - Rank-focused display

*Examples:*
`[leaderboard competition_id="123" time_period="this_week" limit="25"]` - Weekly competition leaderboard
`[competition_history format="achievement_emoji"]` - Emoji-style history display

== Field Reference for Form Mapping ==

When creating application forms, map to these contestant fields:

**Personal Information**
- `first_name` - Legal first name
- `last_name` - Family name/surname  
- `other_names` - Middle names or aliases
- `date_of_birth` - Auto-calculates age
- `gender` - (male, female, other, prefer_not_to_say)
- `location` - City, State, Country
- `email` - Email address
- `phone` - Phone number
- `address` - Full physical address

**Social Media Links**
- `facebook_url` - Facebook profile URL
- `instagram_url` - Instagram profile URL
- `twitter_url` - Twitter/X profile URL
- `youtube_url` - YouTube channel URL
- `tiktok_url` - TikTok profile URL
- `website_url` - Personal/business website

**Visual Media**
- `video_url` - Video introduction URL
- `lifestyle_video_url` - Lifestyle video URL
- `contestant_gallery1` - Gallery image 1
- `contestant_gallery2` - Gallery image 2
- `contestant_gallery3` - Gallery image 3
- `contestant_gallery4` - Gallery image 4

**Competition & Application**
- `current_competition_id` - ⭐ CRITICAL: Competition relationship field
- `talent_category` - Main talent/skill category
- `application_date` - Application submission date
- `application_status` - (pending, approved, rejected, disqualified)

**WordPress Core Fields**
- `post_title` - Contestant display name
- `post_content` - Bio/description
- `featured_image` - Profile photo

== Complete Workflow Example ==

1. **Setup Competition**
   ```
   Competition: "Summer Photo Contest"
   Dates: June 1-30, 2024
   Entry: Free
   Prizes: $1,000 first prize
   Voting: $1 per vote, 10 votes max per user
   ```

2. **Create Application Page**
   ```
   Page: /apply/
   Content: [apply_now_button]
   Form: Forminator form mapped to contestant fields
   ```

3. **Promote Competition**
   ```
   Competition Page: /competitions/summer-photo-contest/
   Content: Competition details + [apply_now_button]
   Leaderboard: [leaderboard competition_id="123"]
   ```

4. **Manage Contestants**
   ```
   Admin: Cordial Contests > Contestants
   View: Applications, approve contestants, monitor votes
   ```

5. **Track Results**
   ```
   Live Leaderboard: [leaderboard competition_id="123"]
   Contestant Pages: Automatic profile pages with voting
   Analytics: Vote history and engagement metrics
   ```

== Troubleshooting ==

= Votes not counting after payment =
- Verify WooCommerce order status is "processing" or "completed"
- Check vote product detection in settings
- Ensure vote product is published and in stock

= Contestants not appearing in competition =
- Verify `current_competition_id` is set in contestant meta
- Check form mapping for competition ID field
- Ensure competition is published and open

= Leaderboard not updating =
- Clear plugin cache in Settings > Advanced
- Check for JavaScript errors in browser console
- Verify vote counting in contestant meta (`vote_count` field)

= Form submissions not creating contestants =
- Verify post_type is set to "contestant"
- Check field mapping matches exact meta field names
- Test form without required fields to identify issues

== Upgrade Notice ==

= 1.0.2 =
Major architectural update with improved data integrity, enhanced admin interface, and universal form support. Recommended for all users.

= 1.0.1 =  
Added smart vote detection and enhanced voting system. Update for better performance and reliability.

= 1.0.0 =
Initial stable release. Safe for production use.

== Changelog ==

= 1.0.2 - 2025-11-21 =
* REMOVED: Competition Assignment metabox to prevent data destruction and maintain form-based integrity
* CHANGED: Disqualification Reason field from text input to textarea for detailed admin notes
* ADDED: Excerpt support for both Competitions and Contestants post types
* FIXED: Data integrity protection - frontend forms now exclusively control competition assignment
* ENHANCED: Admin interface cleanup with simplified contestant management
* ADDED: Personal Information metabox with First Name, Last Name, Other Names fields
* ADDED: Competition History Tracking metabox with current competition and history display
* ADDED: Visual Media metabox with video URLs and photo gallery uploader
* ADDED: 6 competition history display formats with inline radio buttons
* MOVED: Talent category from Bio & Media to Competition History Tracking
* REMOVED: Short Bio field (using post content instead for better compatibility)
* RENAMED: Bio & Media metabox to Visual Media for clarity
* ENHANCED: Competition assignment system with automatic history tracking
* FIXED: Gallery fields now use WordPress media uploader instead of URL input
* FIXED: Competition history radio buttons now inline for better user experience

= 1.0.1 - 2025-01-20 =
* ADDED: Admin-configurable vote product detection with manual ID and custom keyword options
* ADDED: Language-agnostic voting system supporting any language
* ADDED: Flexible detection methods (Manual ID, Keyword Search, Auto-detect) with radio buttons
* ENHANCED: Multi-language support for vote product detection
* REMOVED: Legacy product ID 84 dependency and backup mode logic
* REMOVED: ACF dependency - now uses native WordPress meta for better compatibility
* SIMPLIFIED: Cleaner status reporting without confusing backup mode messages
* IMPROVED: Clear status reporting with detection method transparency
* INTEGRATED: Complete voting system with WooCommerce integration
* INTEGRATED: Time-based ranking system with caching for performance
* INTEGRATED: Leaderboard with multiple filter options and time periods
* INTEGRATED: Contestant cards with voting interface and quantity selection
* INTEGRATED: Competition status automation and management
* INTEGRATED: Vote history tracking and analytics in database
* INTEGRATED: Admin status monitoring and email alerts for system health
* ENHANCED: All existing metaboxes now connected to voting engine
* FIXED: Data structure consistency between competition and contestant systems
* FIXED: Race condition protection for accurate vote counting
* FIXED: Anti-cheating measures and vote cooldowns

= 1.0.0 - 2025-11-19 =
* FIXED: Admin menu labels now show "Add Competition" and "Add Contestant" instead of "Add Post"
* ADDED: Competition assignment metabox for contestants to replace ACF functionality
* ADDED: Proper post type labels for all admin interface elements
* ADDED: Security nonces for metabox data saving
* ADDED: Competition relationship storage via post meta
* ADDED: Plugin settings page with 7 configuration tabs (General, Voting, Competitions, Contestants, Leaderboard, Emails, Advanced)
* ADDED: Complete settings fields for all configuration tabs
* FIXED: Plugin now properly appears in WordPress plugins list
* ADDED: Reorganized admin menu structure with hierarchical layout
* ADDED: Professional menu icon (dashicons-awards)
* ADDED: Comprehensive competition metaboxes (Dates, Pricing, Voting, Rules, Status)
* ADDED: Comprehensive contestant metaboxes (Personal Info, Social Media, Application, Bio, Admin)
* FIXED: Critical errors from external dependencies and save functions
* ADDED: Improved inline field layouts and ALL CAPS metabox titles
* ADDED: Auto-calculated age from date of birth
* Initial release with basic contest system
* Custom post types for competitions and contestants
* Voting shortcodes and interface
* Leaderboard framework
* Forminator integration support
```
=============================================
OUR COMMITMENT TO YOU
Quick Tips for Maintenance
-- Update changelog with every version change.

-- Add new shortcode parameters as we create them.

-- Include new FAQs as users ask questions.

-- Document bug fixes and improvements.


This comprehensive documentation covers every aspect of your plugin and provides users with complete guidance from installation to advanced customization!